Cs 10652/introduce the cardthumbnail inside cardinfofield by lucaslyl · Pull Request #4341 · cardstack/boxel

lucaslyl · 2026-04-07T09:04:57Z

linear: https://linear.app/cardstack/issue/CS-10652/introduce-the-cardthumbnail-inside-cardinfofield

Fix cyclic deps:

Move FileDef, ImageDef, and NumberField into card-api; add cardThumbnail field to CardInfo
Consolidate definitions into card-api: FileDef, ImageDef, and NumberField have been moved into card-api.gts as their canonical home. file-api.gts and image-file-def.gts now re-export from card-api via shim modules to preserve backward compatibility for existing consumers.
Update canonical module URLs: Since FileDef and ImageDef are now canonically defined in card-api, all test fixtures, query filters, and module references that previously pointed to file-api or image-file-def have been updated to point to card-api.
Add cardThumbnail field to CardInfo: CardInfo now has a cardThumbnail field that links to an ImageDef. The existing cardThumbnailURL string field is kept for backward compatibility. CardDef.cardThumbnailURL (the computed field) now resolves cardThumbnail?.url first, falling back to cardThumbnailURL if no image is linked — so the linked image automatically becomes the OG image.

Demo:

Screen.Recording.2026-04-09.at.5.33.24.PM.mov

github-actions · 2026-04-07T09:12:21Z

Preview deployments

github-actions · 2026-04-07T09:40:50Z

Host Test Results

1 files + 1 1 suites +1 2h 26m 4s ⏱️ + 2h 26m 4s
2 194 tests +2 194 2 154 ✅ +2 154 15 💤 +15 0 ❌ ± 0 25 🔥 +25
2 194 runs +2 194 2 129 ✅ +2 129 15 💤 +15 25 ❌ +25 25 🔥 +25

For more details on these errors, see this check.

Results for commit fa904a6. ± Comparison against base commit dffc745.

♻️ This comment has been updated with latest results.

github-actions · 2026-04-07T09:42:40Z

Realm Server Test Results

1 files ±0 1 suites ±0 13m 57s ⏱️ -4s
843 tests ±0 835 ✅ - 8 0 💤 ±0 8 ❌ + 8
914 runs ±0 903 ✅ - 11 0 💤 ±0 11 ❌ +11

For more details on these failures, see this check.

Results for commit fa904a6. ± Comparison against base commit dffc745.

♻️ This comment has been updated with latest results.

… canonical module URL

…cardinfofield

lucaslyl · 2026-04-09T09:44:32Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8747621238

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-09T09:50:27Z

packages/base/image-file-def.gts

-  static atom: BaseDefComponent = Atom;
-  static fitted: BaseDefComponent = Fitted;
-}
+export { ImageDef as default } from './card-api';


Re-export ImageDef as named export from image-file-def

image-file-def previously exposed ImageDef as a named export, but this shim now exports only default. Any existing card/module that still does import { ImageDef } from 'https://cardstack.com/base/image-file-def' will fail module loading with a missing export error, which breaks the stated backward-compatibility goal for the shim and can break existing realms at runtime.

Useful? React with 👍 / 👎.

Copilot

Pull request overview

This PR consolidates FileDef, ImageDef, and NumberField into packages/base/card-api.gts (to break cyclic deps), updates canonical FileDef module references from file-api to card-api, and introduces a new cardThumbnail relationship on CardInfo to support a linked thumbnail image.

Changes:

Move FileDef, ImageDef, and NumberField implementations into card-api.gts, converting file-api.gts, image-file-def.gts, and number.gts into shim/re-export modules.
Add CardInfo.cardThumbnail (links to ImageDef) and update CardDef.cardThumbnailURL to prefer the linked image URL with fallback to the legacy string field.
Update query filters / fixtures / index assumptions and test expectations to use card-api as the canonical FileDef module reference.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/runtime-common/realm-index-query-engine.ts	Default `FileDef` adoptsFrom module updated to `card-api`.
packages/runtime-common/constants.ts	`baseFileRef` now points at `card-api` instead of `file-api`.
packages/realm-server/tests/search-prerendered-test.ts	Test query filter updated to `card-api` `FileDef`.
packages/realm-server/tests/realm-endpoints/search-test.ts	Test filters updated to `card-api` `FileDef`.
packages/realm-server/tests/prerendering-test.ts	Prerender test fixture updated to `card-api` `FileDef`.
packages/realm-server/tests/indexing-test.ts	Indexed doc fixture updated to `card-api` `FileDef`.
packages/host/tests/unit/services/render-service-test.ts	File meta adoptsFrom fixture updated to `card-api`.
packages/host/tests/integration/store-test.gts	File meta adoptsFrom fixtures updated to `card-api`.
packages/host/tests/integration/resources/search-test.ts	Search filters updated to `card-api` `FileDef`.
packages/host/tests/integration/resources/search-data-test.ts	Data search filter updated to `card-api` `FileDef`.
packages/host/tests/integration/realm-querying-test.gts	Querying tests now use `card-api` `FileDef` refs.
packages/host/tests/integration/realm-indexing-test.gts	Expected dependency references updated for moved implementations/new imports.
packages/host/tests/integration/components/prerendered-card-search-test.gts	Query filter updated to `card-api` `FileDef`.
packages/host/tests/integration/components/file-def-serialization-test.gts	Serialization expectation updated to `card-api` `FileDef`.
packages/host/tests/helpers/interact-submode-setup.gts	Dynamic import adjusted for `image-file-def` default export.
packages/host/tests/cards/file-query-card.gts	Query card’s filter updated to `card-api` `FileDef`.
packages/experiments-realm/image-def-playground.gts	Import `ImageDef` now comes from `card-api`.
packages/experiments-realm/file-search-playground.gts	Query filters updated to `card-api` `FileDef`.
packages/base/webp-image-def.gts	Updated `ImageDef` import to match new default export shim.
packages/base/svg-image-def.gts	Updated `ImageDef` import to match new default export shim.
packages/base/png-image-def.gts	Updated `ImageDef` import to match new default export shim.
packages/base/number.gts	Shim now re-exports `NumberField` + helpers from `card-api`.
packages/base/jpg-image-def.gts	Updated `ImageDef` import to match new default export shim.
packages/base/image-file-def.gts	Converted to shim re-exporting `ImageDef` from `card-api`.
packages/base/gif-image-def.gts	Updated `ImageDef` import to match new default export shim.
packages/base/file-api.gts	Converted to shim re-exporting `FileDef` and related helpers/types from `card-api`.
packages/base/default-templates/card-info.gts	Adds `cardThumbnail` editor UI and adjusts thumbnail placeholder logic.
packages/base/card-api.gts	New canonical home for `FileDef`, `ImageDef`, `NumberField`, and adds `CardInfo.cardThumbnail` + updated `cardThumbnailURL` behavior.
packages/base/avif-image-def.gts	Updated `ImageDef` import to match new default export shim.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-09T13:19:42Z

packages/base/image-file-def.gts

-  static atom: BaseDefComponent = Atom;
-  static fitted: BaseDefComponent = Fitted;
-}
+export { ImageDef as default } from './card-api';


image-file-def.gts used to export a named ImageDef class, but now the shim only re-exports it as the module default. That breaks existing consumers that import { ImageDef } from https://cardstack.com/base/image-file-def. To preserve backward compatibility, re-export ImageDef as a named export as well (and optionally keep the default export).

Suggested change

export { ImageDef as default } from './card-api';

export { ImageDef, ImageDef as default } from './card-api';

Copilot · 2026-04-09T13:19:42Z

packages/base/card-api.gts

  @field cardThumbnailURL = contains(MaybeBase64Field, {
    computeVia: function (this: CardDef) {
-      return this.cardInfo.cardThumbnailURL;
+      return this.cardInfo.cardThumbnail?.url ?? this.cardInfo.cardThumbnailURL;


The new cardThumbnailURL computeVia reads this.cardInfo.cardThumbnail?.url. Accessing a linksTo field triggers lazilyLoadLink() when the relationship is not loaded, which will start an async store.loadFileMetaDocument() fetch even though this computeVia can’t await it and will usually fall back to cardThumbnailURL anyway. This can introduce unnecessary background loads/N+1 behavior during serialization/prerendering. Consider avoiding the linksTo getter here (e.g., inspect the raw stored relationship value first, or only use cardThumbnail?.url when the linked ImageDef is already loaded).

Suggested change

return this.cardInfo.cardThumbnail?.url ?? this.cardInfo.cardThumbnailURL;

let rawCardThumbnail = getDataBucket(this.cardInfo).get('cardThumbnail');

let loadedThumbnailURL =

rawCardThumbnail &&

typeof rawCardThumbnail === 'object' &&

'url' in rawCardThumbnail &&

typeof rawCardThumbnail.url === 'string'

? rawCardThumbnail.url

: undefined;

return loadedThumbnailURL ?? this.cardInfo.cardThumbnailURL;

this is a really bad suggestion. it should be ok to pull on a linksTo field in the computed. we will only lazily load it if this field is included in a template, which is exactly the behavior that we want. we should NEVER reach directly into the low level data bucket for a card. that is not a userland API. ignore this review comment

Agreed with it. Sometimes Copilot gives feedback that feels a bit aggressive, which is not the behavior we want.

burieberry

To keep the amount of code added to the card-api to a minimum, you can place any large component or helpers/etc that doesn't cause cyclic error outside of the card-api. You'll see we're doing this with a bunch of templates in /default-templates.

…cardinfofield

lucaslyl force-pushed the CS-10652/introduce-the-cardthumbnail-inside-cardinfofield branch from 24941df to 5d71e37 Compare April 7, 2026 09:18

cardstack deleted a comment from chatgpt-codex-connector bot Apr 7, 2026

lucaslyl added 2 commits April 9, 2026 12:38

Move FileDef, ImageDef, and NumberField into card-api

6d14d23

Update ImageDef consumers to use default image-file-def import

485ed43

lucaslyl force-pushed the CS-10652/introduce-the-cardthumbnail-inside-cardinfofield branch from f681244 to 485ed43 Compare April 9, 2026 04:40

lucaslyl added 5 commits April 9, 2026 15:45

fix: update FileDef module refs from file-api to card-api, making its…

0eceb9c

… canonical module URL

fix prerenderedtest

ea4205b

Merge branch 'main' into CS-10652/introduce-the-cardthumbnail-inside-…

871a2ba

…cardinfofield

add cardThumbnail field

3492085

fix test

8747621

lucaslyl self-assigned this Apr 9, 2026

lucaslyl requested a review from a team April 9, 2026 09:44

lucaslyl marked this pull request as ready for review April 9, 2026 09:45

chatgpt-codex-connector bot reviewed Apr 9, 2026

View reviewed changes

habdelra requested a review from Copilot April 9, 2026 13:13

Copilot started reviewing on behalf of habdelra April 9, 2026 13:14 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

burieberry reviewed Apr 9, 2026

View reviewed changes

lucaslyl added 2 commits April 10, 2026 11:13

Merge branch 'main' into CS-10652/introduce-the-cardthumbnail-inside-…

9e75232

…cardinfofield

fix test

fa904a6

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cs 10652/introduce the cardthumbnail inside cardinfofield#4341

Cs 10652/introduce the cardthumbnail inside cardinfofield#4341
lucaslyl wants to merge 9 commits intomainfrom
CS-10652/introduce-the-cardthumbnail-inside-cardinfofield

lucaslyl commented Apr 7, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 7, 2026

Uh oh!

github-actions bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

lucaslyl commented Apr 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Apr 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

habdelra Apr 9, 2026

Uh oh!

lucaslyl Apr 9, 2026

Uh oh!

burieberry left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	export { ImageDef as default } from './card-api';
	export { ImageDef, ImageDef as default } from './card-api';

-      return this.cardInfo.cardThumbnail?.url ?? this.cardInfo.cardThumbnailURL;
+      let rawCardThumbnail = getDataBucket(this.cardInfo).get('cardThumbnail');
+      let loadedThumbnailURL =
+        rawCardThumbnail &&
+        typeof rawCardThumbnail === 'object' &&
+        'url' in rawCardThumbnail &&
+        typeof rawCardThumbnail.url === 'string'
+          ? rawCardThumbnail.url
+          : undefined;
+      return loadedThumbnailURL ?? this.cardInfo.cardThumbnailURL;

Conversation

lucaslyl commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Demo:

Uh oh!

github-actions bot commented Apr 7, 2026

Preview deployments

Uh oh!

github-actions bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

github-actions bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Realm Server Test Results

Uh oh!

lucaslyl commented Apr 9, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

habdelra Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

lucaslyl Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

burieberry left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lucaslyl commented Apr 7, 2026 •

edited

Loading

github-actions bot commented Apr 7, 2026 •

edited

Loading

github-actions bot commented Apr 7, 2026 •

edited

Loading